GitLab CI 語法與變數整理

TLDR

• GitLab CI 的核心設定檔為 .gitlab-ci.yml，定義了 Pipeline 的執行邏輯。
• 建議優先使用 rules 取代舊版的 only/except，以獲得更精確的執行控制。
• 變數引用建議使用 ${VARIABLE_NAME} 格式，以避免與後續文字混淆。
• workflow:rules 可用於控制整個 Pipeline 的觸發條件（如僅在特定分支或合併請求時執行）。
• needs 關鍵字可打破 Stage 的順序限制，讓 Job 在依賴的 Job 完成後立即執行。
• 善用 artifacts 與 cache 可有效傳遞檔案並加速後續 Job 的執行。

---

基本結構與流程控制

GitLab CI 的 Pipeline 由 .gitlab-ci.yml 定義。為了維護方便，建議將大型設定拆分為多個檔案（如 .gitlab-ci-deploy.yml），並透過 include 引入。

Stages 與 Jobs

• Stages：定義執行順序。同一 Stage 下的 Jobs 會並行執行，且必須全部成功才會進入下一階段。
• Jobs：實際執行的最小單位。命名建議採用「動作-物件-環境」模式（例如 deploy-staging）。

Rules 與 Workflow

• Rules：定義 Job 的執行條件。當規則符合時，依據 when 決定是否執行。
• Workflow：控制整個 Pipeline 的建立條件。若所有規則評估為 when: never，則整個 Pipeline 不會執行。

TIP

官方推薦使用 rules 取代 only/except，因為前者支援更複雜的邏輯判斷，例如：

rules:
  - if: $CI_COMMIT_BRANCH == "main"
    when: always
  - when: never

---

資源管理與優化

Cache 與 Artifacts

• Cache：用於儲存跨 Job 的檔案（如 node_modules/），加速後續建置。建議使用 ${CI_COMMIT_REF_SLUG} 作為 Key。
• Artifacts：用於儲存 Job 產生的成品（如編譯後的 binary），可供後續 Job 下載使用。

Needs

若希望某個 Job 不必等待整個 Stage 完成，只要其依賴的特定 Job 結束即可執行，可使用 needs：

job2:
  stage: test
  needs:
    - job1
  script:
    - echo "此 Job 在 job1 完成後立即執行"

---

變數使用建議

在 GitLab CI 中，變數可定義為全域或 Job 特定。

• 引用方式：建議一律使用 ${VARIABLE_NAME}。當變數後方緊接其他字元時，此格式能明確界定名稱範圍，避免解析錯誤。
• 命名慣例：建議使用全大寫並以底線區隔，例如 DOCKER_IMAGE_NAME。

---

預定義變數參考

GitLab CI 提供了豐富的預定義變數，以下列出常見類別供查閱：

提交相關變數

變數	描述
CI_COMMIT_SHA	專案建置的提交修訂版本。
CI_COMMIT_REF_NAME	當前分支或標籤名稱。
CI_COMMIT_SHORT_SHA	CI_COMMIT_SHA 的前八個字元。

Job 與 Pipeline 相關變數

變數	描述
CI_JOB_ID	Job 的唯一內部 ID。
CI_PIPELINE_ID	Pipeline 的實例層級唯一 ID。
CI_PIPELINE_SOURCE	Pipeline 的觸發來源（如 push, merge_request_event）。

專案與環境變數

變數	描述
CI_PROJECT_PATH	包含專案名稱的命名空間。
CI_PROJECT_URL	專案的 HTTP(S) 網址。
CI_ENVIRONMENT_NAME	當前 Job 的環境名稱。

WARNING

若需呈現雙大括號（例如在某些腳本模板中），請務必將其置於獨立的程式碼區塊內，避免 Vue 編譯錯誤。

---

異動歷程

1. 2025-04-07

   • 初版文件建立。